home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Networking / GetPPPStatus / AEHelpers.h < prev    next >
Encoding:
Text File  |  2000-09-28  |  13.1 KB  |  405 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        AEHelpers.h
  3.  
  4.     Contains:    Functions to help you when you are building and sending Apple events.
  5.  
  6.     Written by: Andy Bachorski    
  7.  
  8.     Copyright:    Copyright © 1996-1999 by Apple Computer, Inc., All Rights Reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.                 7/22/1999    Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1
  20.                 
  21.  
  22. */
  23. //
  24. // %%%%% need to change calls to object building function to pass a boolean
  25. // %%%%% parameter to control the disposal of descs passed in.
  26.  
  27. #ifndef AEHELPERS
  28. #define AEHELPERS
  29.  
  30.  
  31. //    System includes
  32. #include <AERegistry.h>
  33. #include <AEObjects.h>
  34. #include <AEPackObject.h>
  35. #include <Aliases.h>
  36. #include <Icons.h>
  37. #include <Processes.h>
  38. #include <EPPC.h>
  39.  
  40.  
  41. #ifdef __cplusplus
  42. extern "C" {
  43. #endif
  44.  
  45.  
  46. // *****************************************************************************
  47.  
  48. pascal    OSErr    FindProcessBySignature( const OSType targetType,
  49.                                         const OSType targetCreator,
  50.                                               ProcessSerialNumberPtr psnPtr );
  51.  
  52. /*    The FindProcessBySignature function returns a ProcessSerialNumber
  53.     for a process whose signature (type and creator) matches the input values.
  54.     The ProcessSerialNumber will be kNoProcess is the requested process cannot
  55.     be found. 
  56.  
  57.     targetType        input:    The file type of the process to be found.
  58.     targetCreator    input:    The creator type of the process to be found.
  59.     
  60.     psnPtr            input:    Pointer to a ProcessSerialNumber where the
  61.                             process serial number is returned.
  62.                     output:    Process serial number.
  63.     
  64.     RESULT CODES
  65.     ____________
  66.     noErr               0    No error
  67.     procNotFound    –600    No eligible process with specified descriptor
  68.     ____________
  69. */
  70.  
  71. // *****************************************************************************
  72.  
  73. pascal    OSErr    AEHMakeAppleEventSignatureTarget( const OSType targetType,
  74.                                                   const OSType targetCreator,
  75.                                                   const AEEventClass eventClass,
  76.                                                   const AEEventID eventID,
  77.                                                         AppleEvent *theEvent );
  78.  
  79. /*    Create and return an AppleEvent of the given class and ID. The event will be
  80.     targeted at the process specified by the target type and creator codes, 
  81.     with an AEAddressDesc of type typeProcessSerialNumber.
  82.  
  83.     targetType        input:    The file type of the process to be found.
  84.     targetCreator    input:    The creator type of the process to be found.
  85.     eventClass        input:    The class of the event to be created.
  86.     eventID            input:    The ID of the event to be created.
  87.     
  88.     theEvent        input:    Pointer to an AppleEvent record where the
  89.                             event record will be returned.
  90.                     output:    The Apple event.
  91.     
  92.     RESULT CODES
  93.     ____________
  94.     noErr               0    No error    
  95.     memFullErr        -108    Not enough room in heap zone    
  96.     procNotFound    –600    No eligible process with specified descriptor
  97.     ____________
  98. */
  99.  
  100.  
  101. // *****************************************************************************
  102.  
  103. pascal    OSErr    AEHMakeEventProcessTarget( const ProcessSerialNumberPtr psnPtr,
  104.                                            const AEEventClass eventClass,
  105.                                            const AEEventID eventID,
  106.                                                  AppleEvent *theEvent );
  107.  
  108. /*    Create and return an AppleEvent of the given class and ID. The event will be
  109.     targeted with the provided PSN.
  110.  
  111.     psnPtr            input:    Pointer to the PSN to target the event with.
  112.     eventClass        input:    The class of the event to be created.
  113.     eventID            input:    The ID of the event to be created.
  114.     
  115.     theEvent        input:    Pointer to an AppleEvent record where the
  116.                             event record will be returned.
  117.                     output:    The Apple event.
  118.     
  119.     RESULT CODES
  120.     ____________
  121.     noErr               0    No error    
  122.     memFullErr        -108    Not enough room in heap zone    
  123.     procNotFound    –600    No eligible process with specified descriptor
  124.     ____________
  125. */
  126.  
  127. // *****************************************************************************
  128.  
  129. pascal    OSErr    AEHMakeEventTargetID( const TargetID *targetIDPtr,
  130.                                       const AEEventClass eventClass,
  131.                                       const AEEventID eventID,
  132.                                             AppleEvent *theEvent );
  133.  
  134. // *****************************************************************************
  135.  
  136. pascal    OSErr    AEHMakeAliasDescFromFSSpec( const FSSpecPtr fssPtr,
  137.                                                   AEDesc *aliasDesc );
  138.                                                   
  139. /*    Create and return an AEDesc of type typeAlias using the provided FSSpec.
  140.  
  141.     fssPtr            input:    Pointer to the FSSpec to use.
  142.     
  143.     theEvent        input:    Pointer to null AEDesc.
  144.                     output:    an AEDesc of type typeAlias.
  145.     
  146.     RESULT CODES
  147.     ____________
  148.     noErr               0    No error    
  149.     paramErr         -50    The value of target or alias parameter, or of
  150.                             both, is NIL, or the alias record is corrupt
  151.     memFullErr        -108    Not enough room in heap zone    
  152.     ____________
  153. */
  154.  
  155. // *****************************************************************************
  156.  
  157. pascal OSErr AEHMakeAliasDesc( const AliasHandle aliasHandle,
  158.                                      AEDesc *aliasDesc );
  159.  
  160. /*    Create and return an AEDesc of type typeAlias using the provided 
  161.     alias record.
  162.  
  163.     fssPtr            input:    Handle to an alias record.
  164.     
  165.     theEvent        input:    Pointer to null AEDesc.
  166.                     output:    an AEDesc of type typeAlias.
  167.     
  168.     RESULT CODES
  169.     ____________
  170.     noErr               0    No error    
  171.     memFullErr        -108    Not enough room in heap zone    
  172.     ____________
  173. */
  174.  
  175.  
  176. // *****************************************************************************
  177.  
  178. pascal    OSErr    AEHMakeAliasObjectFromFSSpec( const FSSpecPtr fssPtr,
  179.                                                     AEDesc *containerObj,
  180.                                                     AEDesc *aliasObject );
  181. /*
  182.     Given an FSSpec, return an object descriptor containing an alias,
  183.     contained by a null object.
  184.     
  185.     RESULT CODES
  186.     ____________
  187.     noErr                    0    No error    
  188.     paramErr              -50    The value of target or alias parameter, or of
  189.                                 both, is NIL, or the alias record is corrupt
  190.     memFullErr             -108    Not enough room in heap zone    
  191.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  192.                                 Apple event data type    
  193.     errAEWrongDataType    -1703    Wrong Apple event data type    
  194.     errAENotAEDesc        -1704    Not a valid descriptor record    
  195.     errAEBadListItem    -1705    Operation involving a list item failed    
  196.     ____________
  197. */
  198.  
  199. // *****************************************************************************
  200.  
  201. pascal    OSErr    AEHMakeAliasObject( const AliasHandle aliasHandle,
  202.                                           AEDesc *containerObj,
  203.                                           AEDesc *aliasObject );
  204. /*
  205.     Given an object descriptor, create an new object descriptor containing an
  206.     alias, contained by the input object descriptor.
  207.     
  208.     RESULT CODES
  209.     ____________
  210.     noErr                    0    No error    
  211.     paramErr              -50    Error in parameter list
  212.     memFullErr             -108    Not enough room in heap zone    
  213.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  214.                                 Apple event data type    
  215.     errAEWrongDataType    -1703    Wrong Apple event data type    
  216.     errAENotAEDesc        -1704    Not a valid descriptor record    
  217.     errAEBadListItem    -1705    Operation involving a list item failed    
  218.     ____________
  219. */
  220.  
  221. // *****************************************************************************
  222.  
  223. pascal    OSErr    AEHMakePropertyObject( const DescType propType,
  224.                                              AEDesc *containerObj,
  225.                                              AEDesc *propertyObj );
  226. /*
  227.     Given an object descriptor, create an new object descriptor containing
  228.     an property, contained by the input object descriptor.
  229.     
  230.     RESULT CODES
  231.     ____________
  232.     noErr                    0    No error    
  233.     paramErr              -50    Error in parameter list
  234.     memFullErr             -108    Not enough room in heap zone    
  235.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  236.                                 Apple event data type    
  237.     errAEWrongDataType    -1703    Wrong Apple event data type    
  238.     errAENotAEDesc        -1704    Not a valid descriptor record    
  239.     errAEBadListItem    -1705    Operation involving a list item failed    
  240.     ____________
  241. */
  242.  
  243. // *****************************************************************************
  244. pascal    OSErr    AEHMakeProcessObject( const ProcessSerialNumber *psnPtr,
  245.                                              AEDesc *containerObj,
  246.                                              AEDesc *propertyObj );
  247. // *****************************************************************************
  248.  
  249. pascal    OSErr    AEHMakeSelectionObject( const DescType selection,
  250.                                               AEDesc *containerObj,
  251.                                               AEDesc *propertyObj );
  252. /*
  253.     Given an object descriptor, create an new object descriptor containing
  254.     a selection object using the selection specifier, contained by the 
  255.     input object descriptor.
  256.     
  257.     RESULT CODES
  258.     ____________
  259.     noErr                    0    No error    
  260.     paramErr              -50    Error in parameter list
  261.     memFullErr             -108    Not enough room in heap zone    
  262.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  263.                                 Apple event data type    
  264.     errAEWrongDataType    -1703    Wrong Apple event data type    
  265.     errAENotAEDesc        -1704    Not a valid descriptor record    
  266.     errAEBadListItem    -1705    Operation involving a list item failed    
  267.     __________
  268. */
  269.  
  270. // *****************************************************************************
  271. pascal    OSErr    AEHMakeIconSuite( const AEDescList *iconFamilyRecPtr,
  272.                                         Handle *iconSuitePtr );
  273. // *****************************************************************************
  274.  
  275. pascal    OSErr    AEHMakeIconFamilyRecord( const Handle iconSuite,
  276.                                          const IconSelectorValue iconSelector,
  277.                                                AEDescList *iconFamilyRecPtr );
  278.  
  279. /*    ¶ Make an icon family record containing the icons specified in the
  280.     iconSelector parameter.
  281.     The iconSuite parameter should contain an icon suite, as returned by a
  282.     call to GetIconSuite.
  283.     
  284.     iconSuite            input:    The icon suite to build the record from.
  285.     iconSelector        input:    Which icons to include in the record.
  286.     iconFamilyRecPtr    input:    A null descriptor record.
  287.                         output:    An AERecord that's been coerced to an
  288.                                 icon family record.
  289.     
  290.     Result Codes
  291.     ____________
  292.     noErr                    0    No error    
  293.     paramErr              -50    The value of target or alias parameter, or of
  294.                                 both, is NIL, or the alias record is corrupt
  295.     memFullErr             -108    Not enough room in heap zone    
  296.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  297.                                 Apple event data type    
  298.     ____________
  299.     
  300.     Also see:
  301. */
  302.  
  303. // *****************************************************************************
  304.  
  305. pascal    OSErr    AEHGetHandlerError( const AppleEvent *reply );
  306. /*
  307.     Given a reply event, checks for errors returned by the event handler,
  308.     and returns any that are found.
  309.     
  310.     reply                input:    The reply event to be checked.
  311.  
  312.     RESULT CODES
  313.     ____________
  314.     noErr                    0    No error    
  315.     paramErr              -50    The value of target or alias parameter, or of
  316.                                 both, is NIL, or the alias record is corrupt
  317.     memFullErr             -108    Not enough room in heap zone    
  318.     errAECoercionFail     -1700    Data could not be coerced to the requested 
  319.                                 Apple event data type    
  320.     errAEWrongDataType    -1703    Wrong Apple event data type    
  321.     errAENotAEDesc        -1704    Not a valid descriptor record    
  322.     errAEBadListItem    -1705    Operation involving a list item failed
  323.     
  324.     ????                Pretty much any error, depending on what the handler
  325.                         of the event sent does.
  326.     ____________
  327. */
  328.  
  329. // *****************************************************************************
  330.  
  331. pascal    Boolean    AEHSimpleIdleFunction( EventRecord *event,
  332.                                       long *sleepTime,
  333.                                       RgnHandle *mouseRgn );
  334. /*
  335.     A very simple idle function. It simply ignors an event it receives,
  336.     returns 30 for the sleep time and nil for the mouse region.
  337.     
  338.     Your application would normally supply a more robust idle function,
  339.     especially if you have any window. See the tech note on Pending Update
  340.     Perils.
  341. */    
  342.  
  343. // *****************************************************************************
  344.  
  345. pascal    Boolean    HasAppleEvents( void );
  346. /*
  347.     Calls Gestalt and checks if the Apple Event Manager is available.
  348.     
  349.     Use this routine together with FinderCallsAEProcess to determine which
  350.     suite of events the Finder supports. If FinderCallsAEProcess returns false
  351.     the Finder supports the subset of the older Finder event suite.
  352.  
  353.     RESULT CODES
  354.     ____________
  355.     true    The Apple Event Manager is present
  356.     false    It isn't
  357. */
  358.  
  359. // *****************************************************************************
  360.  
  361. pascal    Boolean    FinderCallsAEProcess( void );
  362. /*
  363.     Calls Gestalt and checks if the Finder calls AEProcessAppleEvent.
  364.     If true, the Finder is version 7.1.3 or later.
  365.     
  366.     Use this routine together with FinderIsOSLCompliant to determine which
  367.     suite of events the Finder supports. If FinderIsOSLCompliant returns false
  368.     the Finder supports the full older Finder event suite.
  369.     
  370.     RESULT CODES
  371.     ____________
  372.     true    The Finder calls supports the full old Finder event suite
  373.     false    It doesn't
  374. */
  375.  
  376. // *****************************************************************************
  377.  
  378. pascal    Boolean    FinderIsOSLCompliant( void );
  379. /*
  380.     Calls Gestalt and checks if the Finder is OSL compliant, i.e., it supports
  381.     the new Finder event suite.
  382.     
  383.     If true, the Finder is version 7.5 or later. This means the Finder supports,
  384.     and that you should use, the new Finder event suite. It also means that 
  385.     support for the events present in old Finder event suite is either missing
  386.     or incomplete.
  387.         
  388.     RESULT CODES
  389.     ____________
  390.     true    The Finder supports the new Finder event suite, not the old
  391.     false    It doesn't
  392. */
  393.  
  394. // *****************************************************************************
  395.  
  396. #ifdef __cplusplus
  397. }
  398. #endif
  399.  
  400. #ifndef COMPILING_MORE_FINDER_EVENTS
  401.     #undef pascal
  402. #endif
  403.  
  404. #endif// AEHELPERS
  405.